home *** CD-ROM | disk | FTP | other *** search
/ Freelog 15 / FREELOG 15.ISO / WebMaster / Perl / PERL5106.ZIP / perl5 / Lib / Win32 / netresource.pm < prev    next >
Encoding:
Perl POD Document  |  1996-01-17  |  9.1 KB  |  364 lines
  1. package Win32::NetResource;
  2.  
  3. require Exporter;
  4. require DynaLoader;
  5. require AutoLoader;
  6.  
  7. @ISA = qw(Exporter DynaLoader);
  8. # Items to export into callers namespace by default. Note: do not export
  9. # names by default without a very good reason. Use EXPORT_OK instead.
  10. # Do not simply export all your public functions/methods/constants.
  11. @EXPORT = qw(
  12.     RESOURCEDISPLAYTYPE_DOMAIN
  13.     RESOURCEDISPLAYTYPE_FILE
  14.     RESOURCEDISPLAYTYPE_GENERIC
  15.     RESOURCEDISPLAYTYPE_GROUP
  16.     RESOURCEDISPLAYTYPE_SERVER
  17.     RESOURCEDISPLAYTYPE_SHARE
  18.     RESOURCEDISPLAYTYPE_TREE
  19.     RESOURCETYPE_ANY
  20.     RESOURCETYPE_DISK
  21.     RESOURCETYPE_PRINT
  22.     RESOURCETYPE_UNKNOWN
  23.     RESOURCEUSAGE_CONNECTABLE
  24.     RESOURCEUSAGE_CONTAINER
  25.     RESOURCEUSAGE_RESERVED
  26.     RESOURCE_CONNECTED
  27.     RESOURCE_GLOBALNET
  28.     RESOURCE_REMEMBERED
  29. );
  30.  
  31. =head1 NAME
  32.  
  33. Win32::NetResource - manage network resources in perl
  34.  
  35. =head1 SYNOPSIS
  36.  
  37.     use Win32::NetResource;
  38.  
  39.     $ShareInfo = {
  40.                     'path' => "C:\\MyShareDir",
  41.                     'netname' => "MyShare",
  42.                     'remark' => "It is good to share",
  43.                     'passwd' => "",
  44.                     'current-users' =>0,
  45.                     'permissions' => 0,
  46.                     'maxusers' => -1,
  47.                     'type'  => 0,
  48.                     };
  49.     
  50.    Win32::NetResource::NetShareAdd( $ShareInfo,$parm )|| die "unable to add share\n";
  51.  
  52.  
  53. =head1 DESCRIPTION
  54.  
  55. This module offers control over the network resources of Win32.Disks,
  56. printers etc can be shared over a network.
  57.  
  58. =head1 DATA TYPES
  59. There are two main data types required to control network resources.
  60. In Perl these are represented by hash types.
  61.  
  62. =over 10
  63. =item %NETRESOURCE
  64.  
  65.         KEY                VALUE
  66.         'Scope'            =>    Scope of an Enumeration
  67.                             RESOURCE_CONNECTED,
  68.                             RESOURCE_GLOBALNET,
  69.                             RESOURCE_REMEMBERED.
  70.  
  71.         'Type'            =>    The type of resource to Enum
  72.                             RESOURCETYPE_ANY    All resources
  73.                             RESOURCETYPE_DISK    Disk resources
  74.                             RESOURCETYPE_PRINT    Print resources
  75.  
  76.         'DisplayType'    =>    The way the resource should be displayed.
  77.                             RESOURCEDISPLAYTYPE_DOMAIN    
  78.                             The object should be displayed as a domain.
  79.                             RESOURCEDISPLAYTYPE_GENERIC    
  80.                             The method used to display the object does not matter.
  81.                             RESOURCEDISPLAYTYPE_SERVER    
  82.                             The object should be displayed as a server.
  83.                             RESOURCEDISPLAYTYPE_SHARE    
  84.                             The object should be displayed as a sharepoint.
  85.  
  86.         'Usage'         =>        Specifies the Resources usage:
  87.                                 RESOURCEUSAGE_CONNECTABLE
  88.                                 RESOURCEUSAGE_CONTAINER.
  89.  
  90.         'LocalName'        =>        Name of the local device the resource is 
  91.                                 connected to.
  92.  
  93.         'RemoteName'    =>        The network name of the resource.
  94.         'Comment'        =>        A string comment.
  95.         'Provider'        =>        Name of the provider of the resource.
  96.  
  97. =back    
  98. =item %SHARE_INFO
  99.  
  100. This hash represents the SHARE_INFO_502 struct.
  101. =over 10
  102.         KEY                    VALUE
  103.         'netname'        =>    Name of the share.
  104.         'type'            =>    type of share.
  105.         'remark'        =>    A string comment.
  106.         'permissions'    =>    Permissions value
  107.         'maxusers'         =>    the max # of users.
  108.         'current-users'    =>    the current # of users.
  109.         'path'            =>    The path of the share.
  110.         'passwd'        =>    A password if one is req'd
  111.  
  112. =back
  113. =head1 FUNCTIONS
  114.  
  115. =head2 NOTE:
  116. all of the functions return FALSE (0) if they fail.
  117.  
  118. =over 10
  119.  
  120. =item GetSharedResources(\@Resources,dwType)
  121.     Creates a list in @Resources of %NETRESOURCE hash references.
  122.  
  123. =item AddConnection(\%NETRESOURCE,$Password,$UserName,$Connection)
  124.     Makes a connection to a network resource specified by %NETRESOURCE
  125.  
  126. =item CancelConnection($Name,$Connection,$Force)
  127.     Cancels a connection to a network resource connected to local device 
  128.     $name.$Connection is either 1 - persistent connection or 0, non-persistent.
  129.  
  130. =item WNetGetLastError($ErrorCode,$Description,$Name)
  131.     Gets the Extended Network Error.
  132.  
  133. =item GetError( $ErrorCode )
  134.     Gets the last Error for a Win32::NetResource call.
  135.  
  136. =item GetUNCName( $UNCName, $LocalPath );
  137.     returns the UNC name of the disk share connected to $LocalPath in $UNCName.
  138.  
  139. =head2 servername is optional for all the calls below. ( if not given the local machine is assumed. )
  140.  
  141. =item NetShareAdd(\%SHARE,$parm_err,$servername = NULL )
  142.     Add a share for sharing.
  143.  
  144. =item NetShareCheck($device,$type,$servername = NULL )
  145.     Check if a share is available for connection.
  146.  
  147. =item NetShareDel( $netname, $servername = NULL )
  148.     Remove a share from a machines list of shares.
  149.  
  150. =item NetShareGetInfo( $netname, \%SHARE,$servername=NULL )
  151.     Get the %SHARE_INFO information about the share $netname on the server $servername.
  152.  
  153. =item NetShareSetInfo( $netname,\%SHARE,$parm_err,$servername=NULL)
  154.     Set the information for share $netname.
  155.  
  156. =back
  157.  
  158. =cut
  159.  
  160. sub AUTOLOAD {
  161.     # This AUTOLOAD is used to 'autoload' constants from the constant()
  162.     # XS function.  If a constant is not found then control is passed
  163.     # to the AUTOLOAD in AutoLoader.
  164.  
  165.     local($constname);
  166.     ($constname = $AUTOLOAD) =~ s/.*:://;
  167.     $val = constant($constname, @_ ? $_[0] : 0);
  168.     if ($! != 0) {
  169.     if ($! =~ /Invalid/) {
  170.         $AutoLoader::AUTOLOAD = $AUTOLOAD;
  171.         goto &AutoLoader::AUTOLOAD;
  172.     }
  173.     else {
  174.         ($pack,$file,$line) = caller;
  175.         die "Your vendor has not defined Win32::File macro $constname, used at $file line $line.
  176. ";
  177.     }
  178.     }
  179.     eval "sub $AUTOLOAD { $val }";
  180.     goto &$AUTOLOAD;
  181. }
  182.  
  183. sub AddConnection
  184. {
  185.     local $NetResource = _hash2NET( $_[0] );
  186.  
  187.     _AddConnection($NetResource,$_[1],$_[2],$_[3]);
  188. }
  189.  
  190.  
  191.  
  192. sub GetSharedResources
  193. {
  194.     ( ref $_[0] == ARRAY )||
  195.         die "GetSharedResources: ARRAY reference required\n";
  196.  
  197.     local $Aref = [];
  198.     local $Href;
  199.     local $Ret;
  200.  
  201.     # Get the shared resources.
  202.  
  203.     $Ret = _GetSharedResources( $Aref ,$_[1] );
  204.     
  205.     #build the array of hashes in $_[0]
  206.     
  207.     foreach ( @$Aref ){
  208.         $Href = _NET2hash( $_ );
  209.         push( @{$_[0]}, $Href );
  210.     }
  211.  
  212.     $Ret;
  213. }
  214.  
  215. sub NetShareAdd
  216. {
  217.     local $ShareInfo;
  218.     $ShareInfo = _hash2SHARE( $_[0] );
  219.     _NetShareAdd($ShareInfo,$_[1],$_[2]);
  220.  
  221. }
  222.  
  223. sub NetShareGetInfo
  224. {
  225.     local $NetInfo,$Val;
  226.     $Val = _NetShareGetInfo( $_[0],$NetInfo,$_[2]);
  227.  
  228.     $_[1] = _SHARE2hash( $NetInfo );    
  229.  
  230.     $Val;
  231. }
  232.  
  233. sub NetShareSetInfo
  234. {
  235.     local $ShareInfo;
  236.     $ShareInfo = _hash2SHARE( $_[3] );
  237.  
  238.     _NetShareSetInfo( $_[0],$_[1],$_[2],$ShareInfo,$_[4]);
  239.  
  240. }
  241.  
  242.  
  243. #These are private functions to work with the ShareInfo structure.
  244. #please note that the implementation of these calls requires the SHARE_INFO_502 level
  245. #of information.
  246.  
  247. sub _SHARE2hash
  248. {
  249.     my $ShareRef = $_[0];
  250.  
  251.     local $netname,$type,$remark,$permissions,$maxusers;
  252.     local $current_users,$path,$passwd;
  253.     
  254.     ($type,$permissions,$maxuses,$current_users,$remark,$netname,$path,$passwd)=
  255.         unpack('i4 A257 A81 A257 A257',$ShareRef);
  256.  
  257.     $Hash={     'netname'        =>    $netname,
  258.                 'type'            =>    $type,
  259.                 'remark'        =>    $remark,
  260.                 'permissions'    =>    $permissions,
  261.                 'maxusers'         =>    $maxuses,
  262.                 'current-users'    =>    $current_users,
  263.                 'path'            =>    $path,
  264.                 'passwd'        =>    $passwd,
  265.             };
  266.  
  267.     $Hash;
  268.  
  269.  
  270. }
  271.  
  272. sub _hash2SHARE
  273. {
  274.     local $Hash = $_[0];
  275.        local $ShareRef;
  276.  
  277.     ( ref $Hash == HASH )||
  278.         die "reference passed is not a hash reference\n";
  279.  
  280.  
  281.     local $netname,$type,$remark,$permissions,$maxusers;
  282.     local $current_users,$path,$passwd;
  283.  
  284.     $netname = $Hash->{'netname'} . "\0";
  285.     $type        =    $Hash->{'type'} . "\0";
  286.     $remark        =    $Hash->{'remark'} . "\0";
  287.     $permissions=    $Hash->{'permissions'} . "\0";
  288.     $maxusers    =    $Hash->{'maxusers'} . "\0";
  289.     $current_users= $Hash->{'current_users'} . "\0";
  290.     $path        =    $Hash->{'path'} . "\0";
  291.     $passwd        =    $Hash->{'passwd'} . "\0";
  292.  
  293.     $ShareRef = pack( 'i4 A257 A81 A257 A257',$type,$permissions,$maxusers,$current_users,$remark,$netname,$path,$passwd);
  294.     
  295.     $ShareRef; 
  296. }
  297.  
  298. #These are private functions to translate the NETRESOURCE structure to a hash
  299. # for manipulation in perl.
  300. #typedef struct _NETRESOURCE {  // nr  
  301. #    DWORD  dwScope; 
  302. #    DWORD  dwType; 
  303. #    DWORD  dwDisplayType; 
  304. #    DWORD  dwUsage; 
  305. #    LPTSTR lpLocalName; 
  306. #    LPTSTR lpRemoteName; 
  307. #    LPTSTR lpComment; 
  308. #    LPTSTR lpProvider; 
  309. #} NETRESOURCE; 
  310.  
  311.  sub _NET2hash
  312. {
  313.     my $netref = $_[0];
  314.      local $Scope,$Type,$DisplayType,$Usage,$LocalName,$RemoteName,$Comment,$Provider;
  315.  
  316.     ($Scope,$Type,$DisplayType,$Usage,$LocalName,$RemoteName,$Comment,$Provider) =
  317.         unpack( "i4 p4", $netref );
  318.  
  319.  
  320. $Hash = {
  321.         'Scope'        =>        $Scope,
  322.         'Type'        =>        $Type,
  323.         'DisplayType'    =>    $DisplayType,
  324.         'Usage'     =>        $Usage,
  325.         'LocalName'    =>        $LocalName,
  326.         'RemoteName'    =>    $RemoteName,
  327.         'Comment'    =>        $Comment,
  328.         'Provider'    =>        $Provider,
  329.         };
  330.  
  331.     $Hash;
  332. }
  333.  
  334. sub _hash2NET
  335. {
  336.     my $hashref = $_[0];
  337.     ( ref $hashref == HASH )|| die "Hash reference required\n";
  338.      local $Scope,$Type,$DisplayType,$Usage,$LocalName,$RemoteName,$Comment,$Provider;
  339.  
  340.     $Scope         =        $hashref->{'Scope'};
  341.     $Type         =         $hashref->{'Type'};
  342.     $DisplayType =        $hashref->{'DisplayType'};
  343.     $Usage         =         $hashref->{'Usage'};
  344.     $LocalName     =        $hashref->{'LocalName'};
  345.     $RemoteName =        $hashref->{'RemoteName'};
  346.     $Comment     =        $hashref->{'Comment'};
  347.     $Provider    =        $hashref->{'Provider'};
  348.  
  349.     $hashref = pack( 'i4 p4',$Scope,$Type,$DisplayType,$Usage,$LocalName,$RemoteName,$Comment,$Provider);
  350.  
  351.     $hashref;
  352.  
  353. }
  354.  
  355.  
  356. bootstrap Win32::NetResource;
  357.  
  358. # Preloaded methods go here.
  359.  
  360. # Autoload methods go after __END__, and are processed by the autosplit program.
  361.  
  362. 1;
  363. __END__
  364.